Add type hints and update docstrings for compact test suite modules by Copilot · Pull Request #1266 · PyThaiNLP/pythainlp

Copilot · 2026-02-03T09:56:05Z

What do these changes do

Adds comprehensive type hints to functions tested in the compact test suite, achieving 100% coverage for:

pythainlp.util.spell_word()
pythainlp.util.thai_word_tone_detector()
pythainlp.transliterate.pyicu.transliterate()
pythainlp.classify.GzipModel.predict()

Updates docstrings to accurately reflect the new type hints, including parameter types, return types, and edge case behavior.

What was wrong

Functions lacked type hints or had mypy errors preventing type checking:

spell_word() and thai_word_tone_detector() accepted str but tests passed None
External library calls in pyicu and numpy operations returned Any, causing mypy errors
Docstrings were outdated with incorrect parameter names, wrong types, and missing documentation for Optional parameters

How this fixes it

Type hints for None handling:

# Before
def spell_word(text: str) -> list[str]:

# After  
def spell_word(text: Optional[str]) -> list[str]:
    if not text:
        return []

Fixed mypy no-any-return errors:

Wrapped pyicu.Transliterator.transliterate() with str() cast
Wrapped numpy.ndarray indexing in GzipModel.predict() with str() cast

Updated docstrings:

Fixed parameter name mismatches (e.g., w → text)
Corrected parameter types to include Optional[str] where applicable
Updated return types to use modern syntax (list[str] instead of List[str])
Fixed incorrect return types (e.g., Tuple[str, str] → list[tuple[str, str]])
Added examples demonstrating None/empty input behavior
Fixed typos and improved clarity

Uses Optional[T] instead of T | None for Python 3.9 compatibility.

Your checklist for this pull request

Passed code styles and structures
Passed code linting checks and unit test

Original prompt

Iterating to incrementally add type hints to submodules,
based on works done in these PRs:
#1262
#1263
#1264
#1265

Strategy

Start with small functions/classes and functions/classes that require few external dependencies.

Moving gradually one function by one function, in the four test suites: starting from "core", then "compact", then "extra", and "noauto".

Goals

Immediate goal for this session - 100% type hints for functions/classes being called in "compact" test suite.

Ultimate goal (outside of this session) is to make the package a typed package, while keeping maintainability.

Instructions

Follow best practices and standard Python type hint patterns.

Start small in the area with high confidence (like highly tested submodules or functions), then gradually grow one submodule at a time.

Use mypy as main assistant.

mypy is already in "dev" extra dependencies in pyproject.toml

mypy configuration is in pyproject.toml

Sometimes mypy may report errors wrongly due to cache issues. Try to reset the cache.

Use pyright, pyrefly, and pytype for second opinions.

Required dependencies for each test suite are in pyproject.toml. Install them to avoid errors. See https://github.com/PyThaiNLP/pythainlp/blob/dev/tests/README.md

Use native type in type hint (list, tuple, .. instead of List, Tuple, ..)

Do not use A | B style Union, use full Union[] instead.

We want to keep compatibility with Python 3.9 strict and allow type inspection tools to work correctly.

When insert typing imports, put it in appropriate location and order

Use "if TYPE_CHECKING import" block when possible.

When reordering the imports, beware of circular import. Read comments near imports to get more information.

Remove unused imports

Do not allow the use of assert in production code (it is only allowed for testing and debugging).

Try to fix the type, the scope logic, or do the casting, before putting #type: ignore comment.

When dealing with types from external libraries:

Check if type information is provided (maybe through stubs). If it is, cast wrapper may not necessary.

If return type is not provided, may be it is appropriate to use # type: ignore[no-any-return] annotation for clarity.

Recheck necessity when do casting.

Recheck necessity of # noqa: and # type: ignore

Provide stubs as necessary.

After changes for type hints, recheck for functionality correctness.

Recheck code, docstring, documentation consistency.

Recheck formatting with ruff

Do another code review

Address code review feedback

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: bact <128572+bact@users.noreply.github.com>

…ve Optional usage Co-authored-by: bact <128572+bact@users.noreply.github.com>

coveralls · 2026-02-03T10:13:43Z

coverage: 65.762% (+0.001%) from 65.761%
when pulling 77e4b8c on copilot/add-type-hints-to-submodules-one-more-time
into 0c21974 on dev.

bact · 2026-02-03T10:15:37Z

@copilot Recheck the docstring and documentation of modified functions/modules. See if they are up to date with the latest type hints.

Co-authored-by: bact <128572+bact@users.noreply.github.com>

Copilot · 2026-02-03T10:19:36Z

@copilot Recheck the docstring and documentation of modified functions/modules. See if they are up to date with the latest type hints.

Updated all docstrings to match the type hints in commit 55f52e9:

Fixed parameter names and types (e.g., w → text, str → Optional[str])
Corrected return type documentation (List[str] → list[str], Tuple[str, str] → list[tuple[str, str]])
Fixed parameter type for k in GzipModel.predict() from str to int
Fixed typo "Internaitonal" → "International" in pyicu
Added examples showing None/empty input behavior

All 19 compact tests pass.

Update the return value for None or empty word in thai_word_tone_detector function.

sonarqubecloud · 2026-02-03T10:28:27Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Initial plan

827a357

Copilot AI assigned Copilot and bact Feb 3, 2026

Copilot started work on behalf of bact February 3, 2026 09:56 View session

bact added the refactoring a technical improvement which does not add any new features or change existing features. label Feb 3, 2026

bact added this to the 5.3 milestone Feb 3, 2026

Copilot AI and others added 2 commits February 3, 2026 10:04

Add type hints to util.spell_words and util.thai for compact test suite

fea4ede

Co-authored-by: bact <128572+bact@users.noreply.github.com>

Fix mypy errors in transliterate.pyicu and classify.param_free, impro…

5b05f78

…ve Optional usage Co-authored-by: bact <128572+bact@users.noreply.github.com>

bact marked this pull request as ready for review February 3, 2026 10:09

Copilot AI changed the title ~~[WIP] Add type hints to submodules incrementally~~ Add type hints to compact test suite modules Feb 3, 2026

Copilot finished work on behalf of bact February 3, 2026 10:11

bact reviewed Feb 3, 2026

View reviewed changes

Comment thread pythainlp/util/thai.py Outdated

Apply suggestion from @bact

216318d

Copilot started work on behalf of bact February 3, 2026 10:16 View session

Update docstrings to match type hints and fix parameter documentation

55f52e9

Co-authored-by: bact <128572+bact@users.noreply.github.com>

Copilot AI changed the title ~~Add type hints to compact test suite modules~~ Add type hints and update docstrings for compact test suite modules Feb 3, 2026

Copilot AI requested a review from bact February 3, 2026 10:20

Copilot finished work on behalf of bact February 3, 2026 10:20

bact added 2 commits February 3, 2026 10:22

Update edge case handling in thai_word_tone_detector

d7a8213

Change return value for empty word case in thai.py

77e4b8c

Update the return value for None or empty word in thai_word_tone_detector function.

bact approved these changes Feb 3, 2026

View reviewed changes

bact merged commit a22ff19 into dev Feb 3, 2026
21 of 32 checks passed

bact deleted the copilot/add-type-hints-to-submodules-one-more-time branch February 3, 2026 10:32

This was referenced Feb 3, 2026

Add type hints to modules in extra test suite #1267

Merged

Verify and fix type hints, annotations, and docstrings #1268

Merged

Add type hints to noauto test suite modules #1269

Merged

This was referenced Feb 3, 2026

Align docstrings with type hints across codebase #1270

Merged

Complete type annotations: 100% functions, 56.56% variables, eliminate 25+ Any types #1272

Merged

Fix lazy import bugs and Python 3.9 type hint compatibility #1274

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add type hints and update docstrings for compact test suite modules - #1266

Add type hints and update docstrings for compact test suite modules#1266
bact merged 7 commits into
devfrom
copilot/add-type-hints-to-submodules-one-more-time

Copilot AI commented Feb 3, 2026 •

edited

Loading

Uh oh!

coveralls commented Feb 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

bact commented Feb 3, 2026

Uh oh!

Copilot AI commented Feb 3, 2026

Uh oh!

sonarqubecloud Bot commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

Copilot AI commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What do these changes do

What was wrong

How this fixes it

Your checklist for this pull request

Strategy

Goals

Instructions

Uh oh!

coveralls commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

bact commented Feb 3, 2026

Uh oh!

Copilot AI commented Feb 3, 2026

Uh oh!

sonarqubecloud Bot commented Feb 3, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 3, 2026 •

edited

Loading

coveralls commented Feb 3, 2026 •

edited

Loading